📨 API de TipoMensagem - Documentação Completa

📋 Visão Geral

A API de TipoMensagem é responsável por toda a gestão de tipos de mensagem, estilos de resposta e tipos de resposta no sistema CordenaAi. Esta API permite configurar diferentes categorias de mensagens, definir como os usuários devem responder a essas mensagens e gerenciar os estilos de interação disponíveis no sistema.

🎯 Endpoints Disponíveis

📝 Tipos de Mensagem

1. GET /api/TipoMensagem/tipos-mensagem

Listar Todos os Tipos de Mensagem

• Descrição: Retorna uma lista completa de todos os tipos de mensagem disponíveis no sistema
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros: Nenhum
• Resposta: Array de objetos TipoMensagemEntity
• Uso: Utilizado em formulários de criação de mensagens, dropdowns de seleção e configurações do sistema

2. POST /api/TipoMensagem/tipos-mensagem

Criar Novo Tipo de Mensagem

• Descrição: Cria um novo tipo de mensagem no sistema
• Método: POST
• Autenticação: Requerida (JWT Bearer Token)
• Body: Objeto CriarTipoMensagemRequest
• Resposta: Objeto TipoMensagemEntity criado com ID gerado
• Uso: Configuração de novos tipos de mensagem pelo administrador

3. GET /api/TipoMensagem/tipos-mensagem/{id}

Obter Tipo de Mensagem por ID

• Descrição: Retorna os dados completos de um tipo de mensagem específico
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do tipo de mensagem
• Resposta: Objeto TipoMensagemEntity completo
• Uso: Visualização de detalhes, edição de tipos de mensagem

4. PUT /api/TipoMensagem/tipos-mensagem/{id}

Atualizar Tipo de Mensagem

• Descrição: Atualiza os dados de um tipo de mensagem existente
• Método: PUT
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do tipo de mensagem
• Body: Objeto AtualizarTipoMensagemRequest
• Resposta: Objeto TipoMensagemEntity atualizado
• Uso: Edição de tipos de mensagem existentes

5. DELETE /api/TipoMensagem/tipos-mensagem/{id}

Excluir Tipo de Mensagem

• Descrição: Remove um tipo de mensagem do sistema
• Método: DELETE
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do tipo de mensagem
• Resposta: Confirmação de exclusão
• Uso: Remoção de tipos de mensagem não utilizados

🎨 Tipos de Resposta

6. GET /api/TipoMensagem/tipos-resposta

Listar Todos os Tipos de Resposta

• Descrição: Retorna uma lista de todos os tipos de resposta disponíveis (palavras simples)
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros: Nenhum
• Resposta: Array de objetos TipoRespostaEntity
• Uso: Configuração de respostas simples em formulários

7. GET /api/TipoMensagem/tipos-resposta/{id}

Obter Tipo de Resposta por ID

• Descrição: Retorna os dados de um tipo de resposta específico
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do tipo de resposta
• Resposta: Objeto TipoRespostaEntity
• Uso: Visualização de detalhes de tipos de resposta

🎭 Estilos de Resposta

8. GET /api/TipoMensagem/estilos-resposta

Listar Todos os Estilos de Resposta

• Descrição: Retorna uma lista de todos os estilos de resposta disponíveis
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros: Nenhum
• Resposta: Array de objetos EstiloRespostaEntity
• Uso: Configuração de interfaces de resposta em formulários

9. POST /api/TipoMensagem/estilos-resposta

Criar Novo Estilo de Resposta

• Descrição: Cria um novo estilo de resposta no sistema
• Método: POST
• Autenticação: Requerida (JWT Bearer Token)
• Body: Objeto CriarEstiloRespostaRequest
• Resposta: Objeto EstiloRespostaEntity criado
• Uso: Configuração de novos estilos de interação

10. GET /api/TipoMensagem/estilos-resposta/{id}

Obter Estilo de Resposta por ID

• Descrição: Retorna os dados completos de um estilo de resposta específico
• Método: GET
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do estilo de resposta
• Resposta: Objeto EstiloRespostaEntity completo
• Uso: Visualização de detalhes, edição de estilos

11. PUT /api/TipoMensagem/estilos-resposta/{id}

Atualizar Estilo de Resposta

• Descrição: Atualiza os dados de um estilo de resposta existente
• Método: PUT
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do estilo de resposta
• Body: Objeto AtualizarEstiloRespostaRequest
• Resposta: Objeto EstiloRespostaEntity atualizado
• Uso: Edição de estilos de resposta existentes

12. DELETE /api/TipoMensagem/estilos-resposta/{id}

Excluir Estilo de Resposta

• Descrição: Remove um estilo de resposta do sistema
• Método: DELETE
• Autenticação: Requerida (JWT Bearer Token)
• Parâmetros:
  • id (path): ID único do estilo de resposta
• Resposta: Confirmação de exclusão
• Uso: Remoção de estilos não utilizados

🔧 Modelo de Dados

Estrutura do TipoMensagemEntity

{
  "id": "integer",
  "tipoMensagem": "string",
  "estiloRespostaId": "integer",
  "criacao": "datetime",
  "usuarioCriacao": "string",
  "atualizacao": "datetime",
  "usuarioAtualizacao": "string"
}

Estrutura do EstiloRespostaEntity

{
  "id": "integer",
  "nome": "string",
  "descricao": "string",
  "tipoControle": "string",
  "opcoesJson": "string",
  "ativo": "boolean",
  "criacao": "datetime",
  "usuarioCriacao": "string",
  "atualizacao": "datetime",
  "usuarioAtualizacao": "string"
}

Estrutura do TipoRespostaEntity

{
  "id": "integer",
  "tipoResposta": "string",
  "criacao": "datetime",
  "usuarioCriacao": "string",
  "atualizacao": "datetime",
  "usuarioAtualizacao": "string"
}

DTOs de Request

CriarTipoMensagemRequest

{
  "tipoMensagem": "string",
  "estiloRespostaId": "integer"
}

CriarEstiloRespostaRequest

{
  "nome": "string",
  "descricao": "string",
  "tipoControle": "string",
  "opcoesJson": "string",
  "ativo": "boolean"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

• JWT Bearer Token no header Authorization
• Permissões específicas baseadas no tipo de usuário:
  • Administradores: Acesso completo a todos os endpoints
  • Usuários normais: Acesso apenas de leitura (GET)
  • Gestores: Acesso limitado para criação e edição

📊 Casos de Uso Principais

1. Configuração de Tipos de Mensagem

POST /api/TipoMensagem/tipos-mensagem
Content-Type: application/json
Authorization: Bearer {token}

{
  "tipoMensagem": "Comunicado Urgente",
  "estiloRespostaId": 1
}

2. Criação de Estilo de Resposta

POST /api/TipoMensagem/estilos-resposta
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "Sim ou Não",
  "descricao": "Resposta simples de confirmação",
  "tipoControle": "sim_nao",
  "opcoesJson": "[\"Sim\", \"Não\"]",
  "ativo": true
}

3. Busca de Tipos de Mensagem

GET /api/TipoMensagem/tipos-mensagem
Authorization: Bearer {token}

4. Atualização de Tipo de Mensagem

PUT /api/TipoMensagem/tipos-mensagem/1
Content-Type: application/json
Authorization: Bearer {token}

{
  "id": 1,
  "tipoMensagem": "Comunicado Importante",
  "estiloRespostaId": 2
}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Tipos de Mensagem

• TipoMensagem: Obrigatório, máximo 100 caracteres
• EstiloRespostaId: Opcional, deve existir no sistema se informado

Estilos de Resposta

• Nome: Obrigatório, máximo 100 caracteres
• TipoControle: Obrigatório, máximo 50 caracteres
• Descrição: Opcional, máximo 500 caracteres
• OpcoesJson: Opcional, formato JSON válido

Tipos de Resposta

• TipoResposta: Obrigatório, máximo 100 caracteres

Regras de Negócio

Tipos de Controle Disponíveis

• sim_nao: Resposta simples de sim ou não
• calendario: Seleção de data através de calendário
• data_hora: Seleção de data e hora específica
• texto: Resposta em texto livre
• multipla_escolha: Seleção de múltiplas opções
• escala: Resposta em escala numérica

Regras Gerais

• Soft Delete: Registros inativados não são excluídos permanentemente
• Auditoria: Todas as operações são logadas
• Integridade: Não é possível excluir tipos/estilos em uso
• Ativo: Estilos podem ser ativados/inativados sem exclusão

🚨 Tratamento de Erros

Códigos de Status HTTP

• 200: Sucesso
• 201: Criado com sucesso
• 400: Dados inválidos
• 401: Não autorizado
• 403: Acesso negado
• 404: Registro não encontrado
• 409: Conflito (nome já existente)
• 500: Erro interno do servidor

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

• Paginação: Listas retornam máximo 100 registros por página
• Rate Limiting: 1000 requests por hora por usuário
• Timeout: 30 segundos por requisição

Otimizações

• Cache: Dados de tipos de mensagem são cacheados por 10 minutos
• Índices: Busca otimizada por nome e tipo
• Compressão: Respostas comprimidas com gzip

🔄 Integração com Outros Módulos

Módulos Relacionados

• Mensagens: Associação obrigatória com tipos de mensagem
• UsuarioPermissaoTipoMensagem: Controle de permissões por usuário
• Respostas: Utilização de estilos de resposta
• Auditoria: Log de todas as operações

📱 Uso em Aplicações

Web App

• Formulários de criação/edição de mensagens
• Configuração de tipos e estilos pelo administrador
• Dropdowns de seleção em interfaces
• Relatórios de configuração

Mobile App

• Seleção de tipos de mensagem
• Interface de respostas baseada em estilos
• Configurações de notificação

🛠️ Manutenção e Monitoramento

Logs Importantes

• Criação de novos tipos de mensagem
• Alterações em estilos de resposta
• Tentativas de acesso não autorizado
• Erros de validação

Métricas Monitoradas

• Número de tipos de mensagem cadastrados
• Taxa de utilização de estilos de resposta
• Tempo de resposta dos endpoints
• Uso de recursos por endpoint

📚 Exemplos Práticos

Fluxo Completo de Configuração

1. Validação de dados no backend pela própria API
2. POST /api/TipoMensagem/estilos-resposta para criar estilo
3. POST /api/TipoMensagem/tipos-mensagem associando ao estilo
4. Configuração de permissões via UsuarioPermissaoTipoMensagem
5. Disponibilização para uso em mensagens

Fluxo de Uso em Mensagens

1. GET /api/TipoMensagem/tipos-mensagem para listar opções
2. Seleção do tipo no formulário de mensagem
3. Carregamento do estilo associado automaticamente
4. Renderização da interface baseada no estilo
5. Processamento da resposta conforme configuração

Fluxo de Atualização

1. GET /api/TipoMensagem/tipos-mensagem/{id} para obter dados atuais
2. Validação de alterações no backend pela própria API
3. PUT /api/TipoMensagem/tipos-mensagem/{id} com dados atualizados
4. Atualização do cache automaticamente
5. Notificação de mudanças para usuários afetados

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi